<HTML><HEAD><TITLE>struct itemplate(clause_start, clause_end, clause_fail, clause_redo, block_start, block_end, block_fail, block_redo, subgoal_start, subgoal_end, subgoal_fail, subgoal_redo, call_start, call_end, call_fail, call_redo, fact, inbetween, result, meta_args, exclude, code_weaver, asserted, module_scope, file_local, goal_expansion)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(instrument)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>struct itemplate(clause_start, clause_end, clause_fail, clause_redo, block_start, block_end, block_fail, block_redo, subgoal_start, subgoal_end, subgoal_fail, subgoal_redo, call_start, call_end, call_fail, call_redo, fact, inbetween, result, meta_args, exclude, code_weaver, asserted, module_scope, file_local, goal_expansion)</H1>
 The template used to guide predicate instrumentation
<H2>Fields</H2><DL>
<DT><EM>clause_start</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>clause_end</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>clause_fail</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>clause_redo</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>block_start</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>block_end</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>block_fail</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>block_redo</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>subgoal_start</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>subgoal_end</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>subgoal_fail</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>subgoal_redo</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>call_start</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>call_end</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>call_fail</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>call_redo</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>fact</EM></DT>
<DD>PredSpec of maximum arity one, the atom 'inherit', or variable
</DD>
<DT><EM>inbetween</EM></DT>
<DD>PredSpec of maximum arity two, the atom 'inherit', or variable
</DD>
<DT><EM>result</EM></DT>
<DD>PredSpec of maximum arity five, the atom 'inherit', or variable
</DD>
<DT><EM>meta_args</EM></DT>
<DD>List of itemplate or variable
</DD>
<DT><EM>exclude</EM></DT>
<DD>List of PredSpec, the atom 'inherit', or variable
</DD>
<DT><EM>code_weaver</EM></DT>
<DD>PredSpec of maximum arity six, the atom 'inherit', or variable
</DD>
<DT><EM>asserted</EM></DT>
<DD>Specific atom, the atom 'inherit' or variable
</DD>
<DT><EM>module_scope</EM></DT>
<DD>Atomic module name, the atom 'inherit' or variable
</DD>
<DT><EM>file_local</EM></DT>
<DD>Specific atom, the atom 'inherit' or variable
</DD>
<DT><EM>goal_expansion</EM></DT>
<DD>Specific atom, the atom 'inherit' or variable
</DD>
</DL>
<H2>Description</H2>
<P>
   The <TT><B>itemplate</B></TT> structure serves as a specification that 
   determines how predicate definitions and calls to predicates are instrumented.
   </P><P>
   An <TT>itemplate</TT> is associated with a predicate whose definition or 
   invocations are to be instrumented. This association is specified as an 
   argument to <TT>instrument:instrument/2</TT> or <TT>instrument:instrument/3</TT> 
   and is of the form: <TT>PredSpec = itemplate{...}</TT>.
   </P><P>
   <TT>PredSpec</TT> is of the form <TT>Module:Functor/Arity</TT>. 
   If the module qualifier is omitted, then <TT>PredSpec</TT> is assumed to 
   be a predicate defined within the calling module context in which 
   <TT>instrument/2</TT> was invoked. The definition context for a module 
   can be wildcarded by specifying the module qualifier as the atom 
   <TT>every_module</TT> or by setting the <TT>itemplate module_scope</TT> 
   field to <TT>every_module</TT>.
   </P><P>
   This has two effects:
   <OL>
   <LI> When instrumenting predicate definitions a template can be applied 
        to a predicate regardless of the module it is defined in.
   <LI> When instrumenting predicate calls a template can be applied to a 
        predicate regardless of whether it is module qualified or not.
   </OL>
   However, as a general rule of thumb, predicate specifications for 
   <TT>PredSpec</TT> and instrumentation predicates within the templates 
   should be correctly module qualified. 
   </P><P>
   When determining whether a predicate is to be instrumented, a template is 
   sought which matches the module qualified <TT>PredSpec</TT>, first using 
   the named module (or current module if unqualified) and then using 
   <TT>every_module</TT> as the module qualifier.
   </P><P>
   Within the template, predicate specifications supplied to its fields 
   determine how predicate instrumentation and invocation proceeds. 
   The template specifies the following instrumentation points:
   <DL><DT>
   <PRE>clause_start</PRE>
   <DD>
   A call to the specified predicate is placed at the beginning of each 
   clause definition of the predicate the template is being applied to.
   <DT>
   <PRE>clause_end</PRE>
   <DD>
   A call to the specified predicate is placed at the end of each clause 
   definition of the predicate the template is being applied to.
   <DT>
   <PRE>clause_fail</PRE>
   <DD>
   A call to the specified predicate is placed such that failure within 
   the clause definition of the predicate the template is being applied 
   to results in its invocation.
   <DT>
   <PRE>clause_redo</PRE>
   <DD>
   A call to the specified predicate is placed such that failure and 
   re-execution (i.e. resatisfiable execution) within the clause 
   definition of the predicate the template is being applied to results 
   in its invocation.
   <DT>
   <PRE>block_start</PRE>
   <DD>
   A call to the specified predicate is placed at the beginning of each 
   conjunction (comma-sequences of subgoals) within the definition of 
   the predicate the template is being applied to.
   <DT>
   <PRE>block_end</PRE>
   <DD>
   A call to the specified predicate is placed at the end of each 
   conjunction within the definition of the predicate the template is 
   being applied to.
   <DT>
   <PRE>block_fail</PRE>
   <DD>
   A call to the specified predicate is placed such that failure of each 
   conjunction within the definition of the predicate the template is being 
   applied to results in its invocation.
   <DT>
   <PRE>block_redo</PRE>
   <DD>
   A call to the specified predicate is placed such that failure and 
   re-execution (i.e. resatisfiable execution) of each conjunction within 
   the definition of the predicate the template is being applied to results 
   in its invocation.
   <DT>
   <PRE>subgoal_start</PRE>
   <DD>
   A call to the specified predicate is placed at the beginning of each 
   subgoal within the definition of the predicate the template is being 
   applied to.
   <DT>
   <PRE>subgoal_end</PRE>
   <DD>
   A call to the specified predicate is placed at the end of each subgoal 
   within the definition of the predicate the template is being applied to.
   <DT>
   <PRE>subgoal_fail</PRE>
   <DD>
   A call to the specified predicate is placed such that failure of each 
   subgoal within the definition of the predicate the template is being 
   applied to results in its invocation.
   <DT>
   <PRE>subgoal_redo</PRE>
   <DD>
   A call to the specified predicate is placed such that failure and 
   re-execution (i.e. resatisfiable execution) of each subgoal within 
   the definition of the predicate the template is being applied to results 
   in its invocation.
   <DT>
   <PRE>call_start</PRE>
   <DD>
   A call to the specified predicate is placed at the beginning of each 
   call invocation of the predicate the template is being applied to.
   <DT>
   <PRE>call_end</PRE>
   <DD>
   A call to the specified predicate is placed at the end of each call 
   invocation of the predicate the template is being applied to.
   <DT>
   <PRE>call_fail</PRE>
   <DD>
   A call to the specified predicate is placed such that failure of a call 
   invocation of the predicate the template is being applied to results in 
   its invocation.
   <DT>
   <PRE>call_redo</PRE>
   <DD>
   A call to the specified predicate is placed such that failure and 
   re-execution (i.e. resatisfiable execution) of a call invocation of the 
   predicate the template is being applied to results in its invocation.
   <DT>
   <PRE>fact</PRE>
   <DD>
   A call to the specified predicate is placed as the clause body of the 
   fact predicate the template is being applied to. A fact is a predicate 
   definition with no defined clause body.
   <DT>
   <PRE>inbetween</PRE>
   <DD>
   A call to the specified predicate is placed at the end of each subgoal 
   of a conjunction within the definition of the predicate the template is 
   being applied to.
   </DL>
   </P><P>
   The default value for the instrumentation predicates is that none are 
   defined and so no instrumentation is performed. This is equivalent to 
   setting the field values explicitly to free variables.
   </P><P>
   The instrumentation predicates must be defined with one of the following 
   signatures:
   <DL><DT>
   Arity 0
   <DD>
   When an arity zero instrumentation predicate is specified, it is invoked 
   with no arguments passed.
   <DT>
   Arity 1
   <DD>
   Each code instrumentation point within a module is uniquely identified 
   by its callsite identifier. The callsite identifier is a monotonically 
   increasing integer incrementing from the initial value of 0. It is the 
   callsite identifier value that is passed to an arity one instrumentation 
   predicate.
   <DT>
   Arity 2
   <DD>
   An arity two instrumentation predicate is passed the callsite identifier 
   in argument position one and an auxiliary variable in argument position 
   two. The same auxiliary variable is passed as argument two to the start, 
   end and fail instrumentation points (i.e. it is common to <TT>clause_start</TT>, 
   <TT>clause_end </TT>, <TT>clause_fail</TT> and <TT>clause_redo</TT> while a 
   different auxiliary variable is common to <TT>block_start</TT>, 
   <TT>block_end</TT>, <TT>block_fail</TT> and <TT>block_redo</TT>, etc).
   </DL>
   </P><P>
   It is anticipated that the callsite identifier be used for executing 
   callsite specific code or storing data pertinent to the callsite in a 
   non-logical store keyed by callsite identifier - 
   <TT>set_callsite_data/2</TT> and <TT>get_callsite_data/2</TT> are provided 
   for exactly this purpose.
   </P><P>
   The auxiliary variable passed as argument two to instrumentation 
   predicates is provided for convenience for capturing 'delta' measurements 
   between the start, end and fail instrumentation points. The variable is a 
   logical variable and while the value passed to the end or fail predicate 
   is guaranteed to be the value bound by the start predicate, backtracking 
   past the start predicate results in the unbinding of the variable. If the 
   captured delta should be retained beyond backtracking then it should be 
   placed in the callsite's non-logical store using <TT>set_callsite_data/2</TT>.
   </P><P>
   The maximum arity of the fact and inbetween point predicates is one - 
   only the callsite identifier is passed, there is no benefit in passing an 
   auxiliary variable.
   </P><P>
   The result instrumentation predicate provides a mechanism for 
   pretty-printing the annotated source code with the instrumentation results 
   gathered during execution. By executing <TT>instrument:module_result/0</TT>
   or <TT>instrument:file_result/1</TT> the predicate specified for result 
   instrumentation within the template is invoked as each of the 
   instrumentation points are encountered for pretty-printing.
   </P><P>
   The result instrumentation predicate must be defined with one of the 
   following signatures:
   <DL> <DT>
   Arity 0
   <DD>
   When an arity zero predicate is specified, it is invoked with no 
   arguments passed.
   <DT>
   Arity 1
   <DD>
   The callsite identifier representing the instrumentation point is 
   passed to an arity one result predicate.
   <DT>
   Arity 2
   <DD>
   The instrumentation point type is passed as argument two of an arity 
   two result predicate. The point type is the atom associated with the 
   point, for example <TT>call_start, call_end, call_fail or call_redo</TT>, 
   etc. 
   <DT>
   Arity 3
   <DD>
   The module into which the file being pretty-printed was instrumented 
   and compiled is passed as argument three of an arity three result predicate.
   <DT>
   Arity 4
   <DD>
   The goal appearing in the source code around which instrumentation was 
   originally placed is passed as argument four of an arity four result 
   predicate.
   <DT>
   Arity 5
   <DD>
   The fifth argument of an arity five result predicate is a result goal 
   that can be returned to the pretty-printer to be placed in the 
   pretty-printed output in the place of the fourth argument goal. This 
   allows the goal to be annotated with commentary or instrumentation results.
   </DL>
   </P><P>
   The <TT>meta_args</TT> field of the <TT>itemplate</TT> structure is 
   applicable only to templates associated with predicates that are 
   meta-predicates. When applicable, <TT>meta_args</TT> is a list of 
   <TT>itemplate</TT>. Each element in the list is a template for the 
   corresponding argument of the meta-predicate. The template defined 
   instrumentation points are applied to the code found inside the 
   meta-predicate at this argument position. For example: 
   <PRE>findall/3 = itemplate{..., meta_args:[_, ITemplateArg2, _]...}</PRE> 
   is an <TT>itemplate</TT> specification describing the instrumentation 
   of the meta-predicate <TT>findall/3</TT>. Argument one and three undergo 
   no instrumentation (denoted by free variables) and argument two is 
   instrumented according to <TT>ITemplateArg2</TT>.
   </P><P>
   Within the meta-predicate argument <TT>itemplate</TT> fields may be 
   specified as being <TT>inherit</TT>-ed. When such a field is specified 
   as inherited it is set to the corresponding value of the template used in 
   instrumenting the definition of the predicate in which the call to the 
   meta-predicate resides. 
   </P><P>
   The <TT>exclude</TT> field of the <TT>itemplate</TT> contains a list of 
   predicate specifications. Any occurrence of such a predicate as a call 
   or subgoal is excluded from application of the instrumentation specified 
   by the enclosing template. The main use of exclusion is in preventing 
   instrumentation application to recursive predicates or built-ins.
   </P><P>
   The <TT>code_weaver</TT> field of the <TT>itemplate</TT> specifies a 
   predicate of arity six that is a compile-time callback allowing arbitrary 
   user code to be woven into the code currently undergoing compilation. The 
   weaving of user code is performed before the insertion of instrumentation 
   predicates. The arguments of the predicate are as follows:
   <DL> <DT>
   File
   <DD>
   The name of the file currently undergoing compilation.
   <DT>
   Code
   <DD>
   The block of code available for manipulation by the user specified code 
   weaving predicate.
   <DT>
   Type
   <DD>
   The ECLiPSe construct type of the 'Code' block, one of: 
   <TT>clause, head, body, fact, variable, conjunction, disjunction, 
   conditional, do, goal</TT>. The decomposition of code blocks into these 
   various constructs is for convenience to save the weaver predicate from 
   having to match out the constructs itself. It is however free to do so 
   by operating solely on the <TT>clause</TT> construct.
   <DT>
   WeavedCode
   <DD>
   The block of code that results from the weaving of the Code' block with 
   the arbitrary user code. 
   <DT>
   Mode
   <DD>
   The mode that code weaving is proceeding in, either <TT>compile</TT>, 
   during compilation, or <TT>print</TT> during pretty-printing.
   <DT>
   Module
   <DD>
   The module the code is being compiled into.
   </DL>
   </P><P>
   The remaining fields of the <TT>itemplate</TT> structure specify the 
   options:
   <DL><DT>
   <TT>asserted</TT> (default:free variable)
   <DD><P>
   The value of asserted may be the atoms: <TT>on</TT>, <TT>off</TT> and 
   <TT>post_compile</TT> or a free variable. When a free variable, the 
   instrumentation predicates are compiled into the code like any other 
   predicates. However, when set to one of the atomic values, the predicates 
   are compiled such that they can be inserted and removed at runtime. This 
   is done efficiently such that there is negligible overhead on execution.
   </P><P>
   The value <TT>on</TT> specifies that the predicates are initially inserted.
   The value <TT>off</TT> that they are removed and <TT> post_compile</TT> 
   that they are not inserted until compilation of the whole file has 
   completed. The <TT>post_compile</TT> option is provided so that 
   instrumentation predicates inserted into predicate definitions that get 
   executed at compile-time do not get executed.
   </P><P>
   During execution, the instrumentation predicates can be inserted and 
   removed using <TT>instrument:instrument_control/2</TT>. 
   <P><DT>
   <TT>module_scope</TT> (default:free variable)
   <DD><P>
   The possible values are an atom representing a module name, the atom 
   <TT>every_module</TT> or a free variable indicating the current module. 
   The value is used to determine the module definition context of 
   unqualified instrumentation predicates or the predicate associated with 
   the template for definition and call instrumentation:
   <DL><DT>
   Named module
   <DD><P>
   The unqualified predicate is qualified with the named module.
   <P><DT>
   Free variable
   <DD><P>
   The unqualified predicate is qualified with the calling module context 
   in which <TT>instrument/2</TT> was first invoked.
   <P><DT>
   <TT>every_module</TT>
   <DD><P>
   The unqualified predicate is qualified with the name of the current 
   compilation module.
   <P></DL><P><DT>
   <TT>file_local</TT> (default:<TT>off</TT>)
   <DD><P>
   Templates persist in a global store between successive calls to 
   <TT>instrument/2</TT> and <TT>instrument/3</TT>. If it is undesirable 
   for a template to be added to the global store (thus making it available 
   for the instrumentation of other files and modules) an <TT>itemplate</TT> 
   may be declared as being applicable to only the file currently being 
   instrumented by setting this option to <TT>on</TT>.
   </P><P>
   The search order for an instrumentation template is first in the file 
   local store and then in the global store.
   <P><DT>
   <TT>goal_expansion</TT> (default:<TT>on</TT>)
   <DD><P>
   Setting this to <TT>off</TT> will suppress goal expansion inlining) 
   during compilation. This may be necessary when the processed code 
   contains predicates that get executed at compile time. 
   </P></DL><P>
<H2>See Also</H2>
<A HREF="../../lib/instrument/erase_all_templates-0.html">erase_all_templates / 0</A>, <A HREF="../../lib/instrument/get_callsite_data-2.html">get_callsite_data / 2</A>, <A HREF="../../lib/instrument/instrument-2.html">instrument / 2</A>, <A HREF="../../lib/instrument/instrument-3.html">instrument / 3</A>, <A HREF="../../lib/instrument/instrument_control-2.html">instrument_control / 2</A>, <A HREF="../../lib/instrument/index.html">library(instrument)</A>, <A HREF="../../lib/instrument/module_callsites-2.html">module_callsites / 2</A>, <A HREF="../../lib/instrument/module_result-0.html">module_result / 0</A>, <A HREF="../../lib/instrument/set_callsite_data-2.html">set_callsite_data / 2</A>, <A HREF="../../lib/instrument/defined_modules-2.html">defined_modules / 2</A>
</BODY></HTML>
